<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>v2.2 major changes - Boost.Outcome documentation</title>
<link rel="stylesheet" href="../css/boost.css" type="text/css">
<meta name="generator" content="Hugo 0.52 with Boostdoc theme">
<meta name="viewport" content="width=device-width,initial-scale=1.0"/>

<link rel="icon" href="../images/favicon.ico" type="image/ico"/>
<body><div class="spirit-nav">
<a accesskey="p" href="../changelog/upgrade_v21_v22.html"><img src="../images/prev.png" alt="Prev"></a>
    <a accesskey="u" href="../changelog.html"><img src="../images/up.png" alt="Up"></a>
    <a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="../history.html"><img src="../images/next.png" alt="Next"></a></div><div id="content">
  <div class="titlepage"><div><div><h1 style="clear: both">v2.2 major changes</h1></div></div></div>
  <p>Major changes in v2.2 over v2.1 are listed here.</p>

<ol>
<li><p>A new trait <code>is_move_bitcopying&lt;T&gt;</code> is added, which opts types into a library-based emulation of
<a href="https://wg21.link/P1029">P1029 <em>move = bitcopies</em></a>. <a href="https://wg21.link/P1028">Experimental <code>std::error</code></a> is opted in by default.
If this trait is true for your <code>T</code> or <code>E</code> type, Outcome will track moved-from status for your type,
and will only call your type&rsquo;s destructor if it was not moved from. If your compiler&rsquo;s optimiser is
sufficiently able to fold code, this improves codegen quality for Experimental Outcome very considerably,
approaching the same gains as P1029 types would have. Note that the empirical performance difference
will likely be nil, but the codegen does look much more elegant.</p></li>

<li><p>If for <code>basic_result&lt;T, E&gt;</code> both <code>T</code> and <code>E</code> are trivially copyable, union-based rather than
struct-based storage will be used. This significantly improves performance in synthetic benchmarks
which do nothing in deep call stacks of function calls except create and return <code>result&lt;T, E&gt;</code>, and
makes Outcome return competitive results to alternative error handling choices, improving comparative
optics. It is not expected that the performance difference will be detectable empirically in real
world code. It is expected that the build time impact of union storage won&rsquo;t be noticeable, as
union storage for trivially copyable types is much easier than for non-TC types.</p>

<p>Note that storage remains struct-based if either <code>T</code> or <code>E</code> is neither trivially copyable nor for
which trait <code>is_move_bitcopying&lt;T&gt;</code> is true. This is because union-based storage for complex
types has significant build time impact, as anyone who has deployed <code>std::variant</code> or
<code>std::expected</code> into globally visible public APIs will have noticed.</p></li>

<li><p>The compile time requirement for <code>E</code> types to have a default constructor is removed.</p></li>

<li><p><code>BOOST_OUTCOME_TRY(var, expr)</code> no longer always declares <code>var</code> as <code>auto &amp;&amp;var</code>, but simply uses it
as is. This allows <code>TRY</code> to initialise or assign. You can use the macro <code>OUTCOME21_TRY</code> if you
want the pre-Outcome v2.2 behaviour. You may find the regular expression <code>_TRY\(([^(]*?),(.*?)\);</code> =&gt;
<code>_TRY(auto &amp;&amp;\1,\2);</code> of use to you when upgrading code.</p></li>

<li><p><code>BOOST_OUTCOME_TRY</code> now declares its internal uniquely named temporary variable which holds the result
of the expression as <code>auto unique = expr</code> instead of <code>auto &amp;&amp;unique = expr</code>. This will cause TRY of
<code>result&lt;UncopyableAndImmovable&gt;</code> and <code>outcome&lt;UncopyableAndImmovable&gt;</code> to fail to compile, whereas
previously they did compile. Another big change in semantic is that TRY now will &lsquo;consume&rsquo; values
moved into it, whereas previously it did not/ The reason for this change was that the previous behaviour
produced undefined behaviour in various corner use cases, particulary in generic code. You can tell
TRY to use references instead of values for its uniquely named temporary <a href="../tutorial/essential/result/try_ref.html">using a special
syntax</a>.</p></li>

<li><p><code>BOOST_OUTCOME_TRY</code> now propagates the value from <a href="../reference/functions/hooks/spare_storage.html" class="api-reference"><code>spare_storage(const basic_result|basic_outcome *) noexcept</code></a>

of the input Result/Outcome into any <a href="../reference/traits/is_failure_type.html" class="api-reference"><code>failure_type&lt;T&gt;</code></a>
 returned by TRY. Result/Outcome
now sets its spare storage value from any <a href="../reference/types/success_type.html" class="api-reference"><code>success_type&lt;T&gt;</code></a>
 or <a href="../reference/traits/is_failure_type.html" class="api-reference"><code>failure_type&lt;T&gt;</code></a>

from which it is constructed. This is a breaking change, as spare storage values were not propagated
beforehand. However this change means that any stack backtrace identifier captured by a failed
result construction hook is now fully propagated from failure point up through all TRY operations
to the code which handles the failure.</p></li>

<li><p><a href="../tutorial/advanced/hooks.html">The ADL discovered event hooks</a> have been replaced
with policy-specified event hooks instead. This is due to brittleness (where hooks would quietly
self-disable if somebody changed something), compiler bugs (a difference in compiler settings causes
the wrong hooks, or some but not all hooks, to get discovered), and end user difficulty in using
them at all. The policy-specified event hooks can be told to default to ADL discovered hooks for
backwards compatibility: set <a href="../reference/macros/enable_legacy_support_for.html" class="api-reference"><code>BOOST_OUTCOME_ENABLE_LEGACY_SUPPORT_FOR</code></a>
 to less than <code>220</code> to
enable emulation.</p></li>
</ol>


        </div><p><small>Last revised: February 23, 2021 at 17:37:27 UTC</small></p>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../changelog/upgrade_v21_v22.html"><img src="../images/prev.png" alt="Prev"></a>
    <a accesskey="u" href="../changelog.html"><img src="../images/up.png" alt="Up"></a>
    <a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="../history.html"><img src="../images/next.png" alt="Next"></a></div></body>
</html>
